home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 June: Reference Library / Dev.CD Jun 96 RL / Dev.CD Jun 96 RL.toast / What's New? / Development Kits / Apple Game Sprockets DR1 / Headers / SoundSprocket.h < prev   
Encoding:
C/C++ Source or Header  |  1996-04-24  |  11.5 KB  |  410 lines  |  [TEXT/MPS ]
  1. /*
  2.  *    File:        SoundSprocket.h
  3.  *    Author(s):    Dan Venolia (DV)
  4.  *
  5.  *    Contents:    Public interfaces for sound localization routines.
  6.  *
  7.  *    Copyright (c) 1996 Apple Computer, Inc.
  8.  */
  9.  
  10. #ifndef __SOUNDSPROCKET__
  11. #define __SOUNDSPROCKET__
  12.  
  13. #include <Types.h>
  14.  
  15. #include <QD3D.h>
  16. #include <QD3DCamera.h>
  17.  
  18. #ifdef __cplusplus
  19. extern "C" {
  20. #endif
  21.  
  22. /*******************************************************************************
  23.  *    • TODO: This stuff will be moved to Errors.h
  24.  ******************************************************************************/
  25. enum {
  26.     nilParmErr        = -1234,
  27.     parmRangeErr,
  28.     invalObjectErr,
  29.     nonNormalErr,
  30.     outOfMemErr,
  31.     corruptionErr,
  32.     tooManyListenersErr,
  33.     notOrthogonalErr,
  34.     wrongVersionErr,
  35.     internalErr,
  36.     tooManySourcesErr,
  37.     notInstalledErr,
  38.     unsupporedHardwareErr,
  39.     zeroScaleErr
  40. };
  41.  
  42.  
  43. /*******************************************************************************
  44.  *    • TODO: This stuff will be moved to Sound.h
  45.  ******************************************************************************/
  46. #include <SoundComponents.h>
  47.  
  48. enum {
  49.     siPreMixerSoundComponent    = 'prmx',
  50.     siPostMixerSoundComponent    = 'psmx',
  51.     kSoundEffectsType            = 'snfx',
  52.     kReverbSubType                = 'revb'
  53. };
  54.  
  55.  
  56. struct SoundComponentLink {
  57.     ComponentDescription     description;/*Describes the sound component*/
  58.     SoundSource             mixerID;    /*Reserved by Apple*/
  59.     SoundSource *            linkID;        /*Reserved by Apple*/
  60. };
  61.  
  62. typedef struct SoundComponentLink SoundComponentLink;
  63. typedef SoundComponentLink *SoundComponentLinkPtr;
  64.  
  65.  
  66. /*******************************************************************************
  67.  *    SndSetInfo/SndGetInfo Messages
  68.  ******************************************************************************/
  69.  
  70. /* Our subtype within kSoundEffectsType for siPreMixerSoundComponent */
  71. enum {
  72.     kSnd3DSubType        = 'snd3'
  73. };
  74.  
  75.  
  76. /* Selectors for sndSetInfo and SndGetInfo */
  77. enum {
  78.     si3DCPULoadLimit    = '3dll',        /* Parameter: UInt32, SndGetInfo only    */
  79.     si3DSetup            = '3dst',        /* Parameter: Snd3DSetup, Set/Get        */
  80.     si3DInfo            = '3dif'        /* Parameter: Snd3DInfo, Set/Get        */
  81. };
  82.  
  83.  
  84. enum {
  85.     kSpeakerKindStereo            = 0,
  86.     kSpeakerKindMono            = 1,
  87.     kSpeakerKindHeadphones        = 2
  88. };
  89.  
  90.  
  91. typedef struct Snd3DSetup {
  92.     UInt32                speakerKind;    /* Speaker configuration                */
  93.     float                speakerAngle;    /* Angle formed by user and speakers    */
  94.  
  95.     UInt32                reserved0;        /* Reserved for future use -- set to 0    */
  96.     UInt32                reserved1;        /* Reserved for future use -- set to 0    */
  97. } Snd3DSetup;
  98.  
  99.  
  100. enum {
  101.     kMediumAir                    = 0,
  102.     kMediumWater                = 1
  103. };
  104.  
  105.  
  106. enum {
  107.     kSourceModeLocalized        = 0,    /* Localized by source position            */
  108.     kSourceModeAmbient            = 1,    /* Coming from all around                */
  109.     kSourceModeBinaural            = 2        /* Already binaurally localized            */
  110.     //• kSourceModeUnfiltered???
  111. };
  112.  
  113.  
  114. typedef struct SourceLocation {
  115.     float                longitude;        /* Angle of the meridian -- pos is up    */
  116.     float                latitude;        /* Angle on the meridian -- pos is left    */
  117.     float                distance;        /* Distance between source and listener    */
  118.     float                projectionAngle;/* Cos(angle) between cone and listener    */
  119.     float                sourceVelocity;    /* Speed of source toward the listener    */
  120.     float                listenerVelocity;/*Speed of listener toward the source    */
  121. } SourceLocation;
  122.  
  123.  
  124. typedef struct VirtualSource {
  125.     float                attenuation;    /* Attenuation factor                    */
  126.     SourceLocation        location;        /* Location of virtual source            */
  127. } VirtualSource;
  128.  
  129.  
  130. typedef struct Snd3DInfo {
  131.     UInt32                cpuLoad;        /* CPU load vs. quality -- 0 is best    */
  132.     
  133.     UInt32                medium;            /* Medium for sound propagation            */
  134.     float                humidity;        /* Humidity when medium is air            */
  135.     float                roomSize;        /* Reverb model -- distance bet. walls    */
  136.     float                roomReflectivity;/*Reverb model -- bounce attenuation    */
  137.     float                reverbAttenuation;/*Reverb model -- mix level            */
  138.  
  139.     UInt32                sourceMode;        /* Type of filtering to apply            */
  140.     float                referenceDistance;/*Nominal distance for recording        */
  141.     float                coneAngleCos;    /* Cos(angle/2) of attenuation cone        */
  142.     float                coneAttenuation;/* Attenuation outside the cone            */
  143.     SourceLocation        currentLocation;/* Location of the sound                 */
  144.  
  145.     UInt32                reserved0;        /* Reserved for future use -- set to 0    */
  146.     UInt32                reserved1;        /* Reserved for future use -- set to 0    */
  147.     UInt32                reserved2;        /* Reserved for future use -- set to 0    */
  148.     UInt32                reserved3;        /* Reserved for future use -- set to 0    */
  149.  
  150.     UInt32                virtualSourceCount;/*Number of reflections                */
  151.     VirtualSource        virtualSource[4];/*The reflections                        */
  152. } Snd3DInfo;
  153.  
  154. /*******************************************************************************
  155.  *    Routines for Maniulating Listeners
  156.  ******************************************************************************/
  157. typedef struct ListenerData*    ListenerReference;
  158.  
  159. OSStatus NewListener(
  160.     ListenerReference*            outListenerReference);
  161.  
  162. OSStatus DisposeListener(
  163.     ListenerReference            inListenerReference);
  164.  
  165. OSStatus SetListenerTransform(
  166.     ListenerReference            inListenerReference,
  167.     const TQ3Matrix4x4*            inTransform);
  168.  
  169. OSStatus GetListenerTransform(
  170.     ListenerReference            inListenerReference,
  171.     TQ3Matrix4x4*                outTransform);
  172.  
  173. OSStatus SetListenerPosition(
  174.     ListenerReference            inListenerReference,
  175.     const TQ3Point3D*            inPosition);
  176.  
  177. OSStatus GetListenerPosition(
  178.     ListenerReference            inListenerReference,
  179.     TQ3Point3D*                    outPosition);
  180.  
  181. OSStatus SetListenerOrientation(
  182.     ListenerReference            inListenerReference,
  183.     const TQ3Vector3D*            inOrientation);
  184.  
  185. OSStatus GetListenerOrientation(
  186.     ListenerReference            inListenerReference,
  187.     TQ3Vector3D*                outOrientation);
  188.  
  189. OSStatus SetListenerUpVector(
  190.     ListenerReference            inListenerReference,
  191.     const TQ3Vector3D*            inUpVector);
  192.  
  193. OSStatus GetListenerUpVector(
  194.     ListenerReference            inListenerReference,
  195.     TQ3Vector3D*                outUpVector);
  196.  
  197. OSStatus SetListenerCameraPlacement(
  198.     ListenerReference            inListenerReference,
  199.     const TQ3CameraPlacement*    inCameraPlacement);
  200.  
  201. OSStatus GetListenerCameraPlacement(
  202.     ListenerReference            inListenerReference,
  203.     TQ3CameraPlacement*            outCameraPlacement);
  204.  
  205. OSStatus SetListenerVelocity(
  206.     ListenerReference            inListenerReference,
  207.     const TQ3Vector3D*            inVelocity);
  208.  
  209. OSStatus GetListenerVelocity(
  210.     ListenerReference            inListenerReference,
  211.     TQ3Vector3D*                outVelocity);
  212.  
  213. OSStatus GetListenerActualVelocity(
  214.     ListenerReference            inListenerReference,
  215.     TQ3Vector3D*                outVelocity);
  216.  
  217. OSStatus SetListenerCPULoad(
  218.     ListenerReference            inListenerReference,
  219.     UInt32                        inCPULoad);
  220.  
  221. OSStatus GetListenerCPULoad(
  222.     ListenerReference            inListenerReference,
  223.     UInt32*                        outCPULoad);
  224.  
  225. OSStatus GetCPULoadLimit(
  226.     UInt32*                        outCPULoadLimit);
  227.  
  228. OSStatus SetListenerMedium(
  229.     ListenerReference            inListenerReference,
  230.     UInt32                        inMedium,
  231.     float                        inHumidity);
  232.  
  233. OSStatus GetListenerMedium(
  234.     ListenerReference            inListenerReference,
  235.     UInt32*                        outMedium,
  236.     float*                        outHumidity);
  237.  
  238. OSStatus SetListenerReverb(
  239.     ListenerReference            inListenerReference,
  240.     float                        inRoomSize,
  241.     float                        inRoomReflectivity,
  242.     float                        inReverbAttenuation);
  243.  
  244. OSStatus GetListenerReverb(
  245.     ListenerReference            inListenerReference,
  246.     float*                        outRoomSize,
  247.     float*                        outRoomReflectivity,
  248.     float*                        outReverbAttenuation);
  249.  
  250. OSStatus SetListenerMetersPerUnit(
  251.     ListenerReference            inListenerReference,
  252.     float                        inMetersPerUnit);
  253.  
  254. OSStatus GetListenerMetersPerUnit(
  255.     ListenerReference            inListenerReference,
  256.     float*                        outMetersPerUnit);
  257.  
  258.  
  259. /*******************************************************************************
  260.  *    Routines for Manipulating Sources
  261.  ******************************************************************************/
  262. typedef struct SourceData*        SourceReference;
  263.  
  264. OSStatus NewSource(
  265.     SourceReference*            outSourceReference);
  266.  
  267. OSStatus DisposeSource(
  268.     SourceReference                inSourceReference);
  269.  
  270. OSStatus GetSource3DInfo(
  271.     SourceReference                inSourceReference,
  272.     ListenerReference            inListenerReference,
  273.     Snd3DInfo*                    out3DInfo);
  274.  
  275. OSStatus SetSourceTransform(
  276.     SourceReference                inSourceReference,
  277.     const TQ3Matrix4x4*            inTransform);
  278.  
  279. OSStatus GetSourceTransform(
  280.     SourceReference                inSourceReference,
  281.     TQ3Matrix4x4*                outTransform);
  282.  
  283. OSStatus SetSourcePosition(
  284.     SourceReference                inSourceReference,
  285.     const TQ3Point3D*            inPosition);
  286.  
  287. OSStatus GetSourcePosition(
  288.     SourceReference                inSourceReference,
  289.     TQ3Point3D*                    outPosition);
  290.  
  291. OSStatus SetSourceOrientation(
  292.     SourceReference                inSourceReference,
  293.     const TQ3Vector3D*            inOrientation);
  294.  
  295. OSStatus GetSourceOrientation(
  296.     SourceReference                inSourceReference,
  297.     TQ3Vector3D*                outOrientation);
  298.  
  299. OSStatus SetSourceUpVector(
  300.     SourceReference                inSourceReference,
  301.     const TQ3Vector3D*            inUpVector);
  302.  
  303. OSStatus GetSourceUpVector(
  304.     SourceReference                inSourceReference,
  305.     TQ3Vector3D*                outUpVector);
  306.  
  307. OSStatus SetSourceCameraPlacement(
  308.     SourceReference                inSourceReference,
  309.     const TQ3CameraPlacement*    inCameraPlacement);
  310.  
  311. OSStatus GetSourceCameraPlacement(
  312.     SourceReference                inSourceReference,
  313.     TQ3CameraPlacement*            outCameraPlacement);
  314.  
  315. OSStatus SetSourceVelocity(
  316.     SourceReference                inSourceReference,
  317.     const TQ3Vector3D*            inVelocity);
  318.  
  319. OSStatus GetSourceVelocity(
  320.     SourceReference                inSourceReference,
  321.     TQ3Vector3D*                outVelocity);
  322.  
  323. OSStatus GetSourceActualVelocity(
  324.     SourceReference                inSourceReference,
  325.     TQ3Vector3D*                outVelocity);
  326.  
  327. OSStatus SetSourceMode(
  328.     SourceReference                inSourceReference,
  329.     UInt32                        inMode);
  330.  
  331. OSStatus GetSourceMode(
  332.     SourceReference                inSourceReference,
  333.     UInt32*                        outMode);
  334.  
  335. OSStatus SetSourceReferenceDistance(
  336.     SourceReference                inSourceReference,
  337.     float                        inReferenceDistance);
  338.  
  339. OSStatus GetSourceReferenceDistance(
  340.     SourceReference                inSourceReference,
  341.     float*                        outReferenceDistance);
  342.  
  343. OSStatus SetSourceSize(
  344.     SourceReference                inSourceReference,
  345.     float                        inLength,
  346.     float                        inWidth,
  347.     float                        inHeight);
  348.  
  349. OSStatus GetSourceSize(
  350.     SourceReference                inSourceReference,
  351.     float*                        outLength,
  352.     float*                        outWidth,
  353.     float*                        outHeight);
  354.  
  355. OSStatus SetSourceAngularAttenuation(
  356.     SourceReference                inSourceReference,
  357.     float                        inConeAngle,
  358.     float                        inConeAttenuation);
  359.  
  360. OSStatus GetSourceAngularAttenuation(
  361.     SourceReference                inSourceReference,
  362.     float*                        outConeAngle,
  363.     float*                        outConeAttenuation);
  364.  
  365.  
  366. /*******************************************************************************
  367.  *    The following is here for use with versions of the Sound Manager before
  368.  *    version 3.2.1d2+ that did not support the siPreMixerSoundComponent message.
  369.  *    To use an older SoundManager, you should #define COMPILE_TIME_PATCH 1 in
  370.  *    your prefix file.  This installs the "compile-time patch" on SndGetInfo
  371.  *    and SndSetInfo to catch the messages that the 3D spatial sound filter
  372.  *    component normally handles.  All other messages are sent down to the real
  373.  *    calls.
  374.  *
  375.  *    Since we are not using the real localization filter component, the effects
  376.  *    are limited to what we can do through the sound channel.  Specifically this
  377.  *    means that we use volumeCmd and rateMultiplierCmd to implement the various
  378.  *    attenuation factors and Doppler effect.  So no reverb effects, etc.
  379.  *
  380.  *    WARNING:    When COMPILE_TIME_PATCH is defined as 1, any volumeCmd and
  381.  *                rateMultiplierCmds that you send to your sound channel are
  382.  *                trounced when SndSetInfo is called with si3DInfo.
  383.  ******************************************************************************/
  384. #ifndef COMPILE_TIME_PATCH
  385.     #define COMPILE_TIME_PATCH        0
  386. #endif
  387.  
  388. #if COMPILE_TIME_PATCH
  389.     #include <Sound.h>
  390.     
  391.     #define SndSetInfo            Patch_SndSetInfo
  392.     #define SndGetInfo            Patch_SndGetInfo
  393.     
  394.     OSErr Patch_SndSetInfo(
  395.         SndChannelPtr            inSndChannel,
  396.         OSType                    inSelector,
  397.         void*                    inData);
  398.     
  399.     OSErr Patch_SndGetInfo(
  400.         SndChannelPtr            inSndChannel,
  401.         OSType                    inSelector,
  402.         void*                    outData);
  403. #endif
  404.  
  405. #ifdef __cplusplus
  406. }
  407. #endif
  408.  
  409. #endif /* __SOUNDSPROCKET__ */
  410.